Parent | Child | Previous | Next
 
Xbasic

HTTP_DOWNLOAD Function

Syntax

Status_Flag as L = http_download([source_url as C [,target_file as C [,modal as L [,pDialogSettings as P]]]])

Arguments

source_urlCharacter

The location of the file to download.

target_fileCharacter

The name of the file to write locally.

modalLogical

Default = .t.. If .T., Modal dialog box. If .F., Modeless dialog box.

pDialogSettingsPointer

Dialog allows properties of the dialog box to be overridden. Available properties are listed below:

close_on_completeLogical

.T. = Closes the dialog when the file is finished downloading or an error is encountered.

launch_on_completeLogical

.T. = Opens the file in its associated application after the download is complete.

title_initialCharacter

Sets the initial dialog title. The default is " File Download"

title_progressCharacter

Sets the dialog title that is displayed as the download progresses. The default is " {percent} of {dl_file}".

Placeholder
Description
{current_bytes}

The running total of bytes downloaded so far .

{total_bytes}

The total number of bytes to be downloaded.

{percent}

The completion percent.

{dl_file}

The name of the file being downloaded.

cancelLogical

.F. = Disables the Cancel button

closeLogical

.F. = Disables the Close button

launchLogical

.F. = Disables the Launch button

fromLogical

.F. = Hides the "download from"

toLogical

.F. = Hides the "save to" display

statusLogical

.F. = Hides the status display (x bytes of xxx bytes)

progressLogical

.F. = Hides the progress bar

error_text_404Character

The error text to be displayed if the server returns a 404 status (file not found). Default is "Server error - file not found"

labelPointer

Label overrides. Available override properties are listed below:

fromCharacter

Allows you to replace the default "Download From: " label.

toCharacter

Allows you to replace the default "Save From: "

statusCharacter

Allows you to replace the default "Status: "

progressCharacter

Allows you to replace the default "Progress: "

closeCharacter

Allows you to replace the label on the Close button

cancelCharacter

Allows you to replace the label on the Cancel button

cancelledCharacter

The text to be displayed on the status line if the download is cancelled by the user. Default is "Download cancelled"

launchCharacter

Allows you to replace the label on the Launch button

urlpromptPointer

Overrides for the URL Prompt. Can have the following properites:

titleCharacter

Allows you to replace the default title on the URL prompt window (which only appears if the URL is not specified).

promptCharacter

Allows you to replace the default prompt on the URL prompt window (which only appears if the URL is not specified).

filepromptPointer

Overrides for the file prompt window. Can have the following properties:

titleCharacter

Allows you to replace the default title on the file prompt window (which only appears if the file is not specified).

Returns

Status_FlagLogical

If Modal is set to TRUE, Status_Flag will be true if the download was successful, FALSE otherwise. If Modal is FALSE, Status_Flag will always be TRUE, because the function call returns before the download is complete.

Description

Download a file via the HTTP protocol and display a progress dialog

Discussion

The HTTP_DOWNLOAD() function shows a progress dialog while downloading a file from the specified URL and saving it to Target_File. The user will be promoted for URL and Target_File if they are omitted. Unlike FTP_GET_FILE(), HTTP_DOWNLOAD() does not have a built-in mechanism to retry when transmission errors occur.

HTTP_DOWNLOAD() cannot be used with an https address. Use HTTP_FETCH() instead.

When the server responds with a 30* code, HTTP_DOWNLOAD() does not automatically use the new URL. The developer needs to examine result.parsed_headers.status_code, then if appropriate, try the URL provided in result.parsed_headers.location. Refer to HTTP_GET() for an example.

Example

Download the AlphaSports Explained PDF from the Learning center, prompting for the location to save the downloaded file.

http_download("http://downloads.alphasoftware.com/Books/AlphaSports.pdf")

Download the Xbasic Guide PDF from the Learning center and save to a predetermined location.

http_download("http://downloads.alphasoftware.com/Books/AlphaSports.pdf", "c:\alphasports.pdf")

Same as above, but make the progress window modal.

http_download("http://downloads.alphasoftware.com/Books/AlphaSports.pdf", "c:\alphasports.pdf", .f.)

Automatically close the progress window on completion.

dim options as P
options.close_on_complete = .t.
http_download("http://downloads.alphasoftware.com/Books/AlphaSports.pdf", "c:\alphasports.pdf", .f., options)

Automatically close the progress window on completion and launch the downloaded file.

dim options as P
options.close_on_complete = .t.
options.launch_on_complete = .t.
http_download("http://downloads.alphasoftware.com/Books/AlphaSports.pdf", "c:\alphasports.pdf", .f., options)

See Also